home *** CD-ROM | disk | FTP | other *** search
/ AmigActive 2 / AACD 2.iso / AACD / Hardware / BetaScan / BetaScanDev / ScannerDev.doc < prev   
Encoding:
Text File  |  1999-01-23  |  6.7 KB  |  232 lines
  1. Making a Scanner Driver
  2. =======================
  3.  
  4. A scanner driver is made as an Amiga Device.
  5.  
  6.  
  7. The Device I/O request
  8. ----------------------
  9.  
  10. The scanner device uses a special I/O request:
  11.  
  12.   struct ScannerIO
  13.   {
  14.     struct IOStdReq       IOScan;
  15.     struct ScannerOptions option;
  16.   }
  17.  
  18. where struct IOStdReq is a standard IO request as defined in exec/io.h and
  19. struct ScannerOptions is defined in the include file scanner.h
  20.  
  21. Before opening the device BetaScan places a pointer to a string containing
  22. the name of the IO unit where the scanner is connected (for instance
  23. scsi.device) in the IOScan.io_Data field. Then the open device is called:
  24.  
  25.   OpenDevice(scannerName,unit,(struct IORequest *)ScannerIO,0)
  26.  
  27. where unit is the unit number of the IO unit.
  28.  
  29. The open routine must do the necessary initializations and then set the fields
  30. in the structure option:
  31.  
  32.   struct ScannerOptions
  33.   {
  34.     char   so_scannerVendor[40];
  35.     char   so_scannerModel[40];
  36.  
  37.     UBYTE  so_driverVersion;
  38.     UBYTE  so_driverRevision;
  39.  
  40.     double so_docWidth;                      /* Paper size in mm             */
  41.     double so_docHeight;
  42.  
  43.     UWORD  so_flags;                        /*  Not used                     */
  44.     UWORD  so_optionNum;                     /* Number of option descriptors */
  45.  
  46.     struct OptionDescriptor* so_descriptor;
  47.   };
  48.  
  49. The structure OptionDescriptor has the form:
  50.  
  51.   struct OptionDescriptor
  52.   {
  53.     OptionId   od_optionID;
  54.     ValueType  od_valueType;
  55.     ValueUnit  od_valueUnit;
  56.     Constraint od_constraintType;
  57.     union
  58.     {
  59.       char** stringList;  /* Null terminated array of string values  */
  60.       int*   numberList;  /* Legal values - numberList[0] = number   */
  61.       Range* numberRange;
  62.     }
  63.     od_constraint;
  64.     void* od_specialInfo; /* See below                               */
  65.   };
  66.  
  67.  
  68. More information in headerfile scanner.h. The following options must be present:
  69.  
  70.   ID_SCANMODE          /* BW, Gray, RGB etc.                 */
  71.   ID_TL_X              /* upper left corner of scan area     */
  72.   ID_TL_Y              /* upper left corner of scan area     */
  73.   ID_BR_X              /* bottom right corner of scan area   */
  74.   ID_BR_Y,             /* bottom right corner of scan area   */
  75.   ID_RESOLUTION        /* scan resolution (combined x and y) */
  76.  
  77.  
  78. IO Commands
  79. -----------
  80.  
  81. The device must respond to the following commands (more info in scanner.h):
  82.  
  83.  CMD_START   - Start scanning
  84.  
  85.    The scanning parameters must have been set before (SCANCMD_CONTROL). The
  86.    IOScan.io_Data field contains a pointer to a structure
  87.  
  88.    struct ScanInformation
  89.    {
  90.      double     sv_xResolution;  /* actual horizontal resolution        */
  91.      double     sv_yResolution;  /* actual vertical resolution          */
  92.      LineFormat sv_lineFormat;   /* format of scan lines                */
  93.      UWORD      sv_imageWidth;   /* image width in pixels               */
  94.      UWORD      sv_imageHeight;  /* image height in pixels              */
  95.      UWORD      sv_imageDepth;   /* image depth in bits                 */
  96.      UWORD      sv_bytesPerLine; /* bytes per line read                 */
  97.      ULONG      sv_Flags;        /* data information flags              */
  98.    }
  99.  
  100.    Most scanners must do some roundings so that your scanner parameters are
  101.    not exactly the actual ones. Fill in the actual parameter values in this
  102.    structure.
  103.  
  104.  CMD_STOP    - Stop scanning
  105.  
  106.    This command is always send (even if the driver has send all scan lines or
  107.    has reported an error).
  108.  
  109.  CMD_READ    - Read one or more scan lines
  110.  
  111.     The IOScan.io_Data field contains a pointer to a scan line structure
  112.  
  113.     struct ScanLine
  114.     {
  115.       UBYTE*     sl_data;
  116.       LineFormat sl_color;   /* If sv_lineFormat is FORMAT_RGB_RANDOM    */
  117.     }                        /* this is either FORMAT_RED, FORMAT_GREEN  */
  118.                              /* or FORMAT_BLUE. Otherwise it must be the */
  119.                              /* same as sv_lineFormat.                   */
  120.  
  121.     IOScan.io_Length the buffer length.
  122.  
  123.     Return the actual number of bytes returned (an integral multiple of
  124.     sv_bytesPerLine).
  125.  
  126.  SCANCMD_CONTROL - Set/Get option values
  127.  
  128.     The field IOScan.io_Data contains a pointer to the structure (found in
  129.     scanner.h):
  130.  
  131.     struct OptionValue
  132.     {
  133.       OptionId sp_optionID;
  134.       int      sp_value;
  135.       ULONG    sp_flags;
  136.     };
  137.  
  138.     sp_optionID field is the indentification number of the option value you
  139.     want to control.
  140.  
  141.     sp_value is the option value send to or returned from the driver. The
  142.     value type is the same as given in the option descriptor. For TYPE_STRING
  143.     the value is the  index value.
  144.  
  145.     sp_flags tells how to control the option. The values are
  146.  
  147.       CONTROL_SET  (1<<0)      /* Set new value              */
  148.       CONTROL_GET  (1<<1)      /* Return current value       */
  149.  
  150.     Both bits can be set. The following bits may be set at return:
  151.  
  152.       CONTROL_ROUNDED    (1<<16)     /* Value set is not exact     */
  153.       CONTROL_RANGE      (1<<17)     /* Out of range - not set     */
  154.       CONTROL_DISABLED   (1<<18)     /* Option disabled - not set  */
  155.       CONTROL_INVALID    (1<<19)     /* Option not supported       */
  156.  
  157.     The command may be send without CONTROL_SET or CONTROL_GET bits set to
  158.     get information about the option.
  159.  
  160.  
  161. Actual development
  162. ------------------
  163.  
  164. To avoid making all the nasty device stuff and to facilitate the testing you
  165. can use the files in the ScannerDev directory (SAS/C 6.57).
  166.  
  167. By using these files you only have to make a single file with the following
  168. routines:
  169.  
  170.   void openScanner(char* name,int unit,struct ScannerOptions* option,BYTE* status)
  171.  
  172.     This is called when the scanner device is opened.
  173.  
  174.     input:
  175.       name:   name of the IO unit
  176.       unit:   number of the IO unit
  177.       option: pointer to the option structure
  178.       status: the return value (io_Error)
  179.  
  180.  
  181.   void closeScanner(void)
  182.  
  183.     Close the scanner
  184.  
  185.  
  186.   void controlOption(struct OptionValue* optVal,BYTE* status)
  187.  
  188.     Set scanning parameters
  189.  
  190.     input:
  191.       optVal: pointer to an OptionValue structure
  192.       status: the return status
  193.  
  194.  
  195.   void startScanning(struct ScanInformation* inform,BYTE* status)
  196.  
  197.     Start the scanning
  198.  
  199.     input:
  200.       inform: a pointer to a ScanInformation structure to be filled by you.
  201.       status: the return value
  202.  
  203.  
  204.   void stopScanning(void)
  205.  
  206.     Stop the scanning
  207.  
  208.  
  209.   void readScanLine(struct ScanLine* line,BYTE* status)
  210.  
  211.     Read one ore more scan line(s)
  212.  
  213.     input:
  214.       line:   pointer to a scan line structure
  215.       status: the return status
  216.  
  217.  
  218. An example file is in ScanDev directory (in fact divided into two: ScanmakerE3.c
  219. and Scsi.c). To make a test version execute the command:
  220.  
  221.    smake -f smakeTest
  222.  
  223.  
  224. The resulting executable is called scanner.
  225.  
  226. To make a device execute
  227.  
  228.    smake -f smakeDevice
  229.  
  230. The linker will make 4 warnings about absolute addressing. Don't care.
  231.  
  232.